feat(util.dataset): add simulate_if_needed one-line auto-simulate helper - #670

Phase 1 of #669.

Summary

• Adds aa.util.dataset.simulate_if_needed(dataset_path, simulator) to autoarray/util/dataset_util.py. When should_simulate(str(dataset_path)) is True it runs subprocess.run([sys.executable, str(simulator)], check=True). It returns whether the simulator ran.
• Uses a subprocess on purpose, not runpy, so the simulator's JAX/matplotlib/module state cannot leak into the calling script. check=True means a failing simulator raises instead of letting the caller load a missing dataset.
• Accepts str or Path for both arguments.
• The usage example in the should_simulate docstring now points at the helper.

This lets workspaces replace the 8-line block:

if al.util.dataset.should_simulate(str(dataset_path)):
    import subprocess
    import sys

    subprocess.run([sys.executable, "scripts/simulator/lens_x2.py"], check=True)

with:

al.util.dataset.simulate_if_needed(dataset_path, simulator="scripts/simulator/lens_x2.py")

The workspace sweep (phase 3) waits for a release. The companion PyAutoHands PR makes check_dataset_allowlist recognise the new call, so swept scripts stay guarded.

Testing

• New tests in test_autoarray/util/test_dataset_util.py mock subprocess.run. They check that it is called exactly once with [sys.executable, str(simulator)] and check=True when should_simulate is True, that it is not called when False, that both str and Path arguments work, and that a missing dataset triggers the run.
• pytest test_autoarray/util: 148 passed.

al.util.dataset / ag.util.dataset should expose the helper automatically, because they re-export this module (the workspaces already call al.util.dataset.should_simulate). That wasn't checked against PyAutoGalaxy/PyAutoLens in this session.

Merge mode: human /prm.

Generated by Claude Code